---
title: "Модуль log-shipper"
description: Описание возможностей сбора логов в кластере Kubernetes с помощью модуля log-shipper Deckhouse. Описание топологий отправки логов, возможностей фильтрации логов и обогащения логов метаданными.
---

Модуль разворачивает агенты `log-shipper` для сборки логов на узлы кластера.
Предназначение этих агентов — с минимальными изменениями отправить логи дальше из кластера.
Каждый агент — это отдельный [vector](https://vector.dev/), конфигурацию для которого сгенерировал Deckhouse.

![log-shipper architecture](../../images/460-log-shipper/log_shipper_architecture.svg)
<!-- Исходник картинок: https://docs.google.com/drawings/d/1cOm5emdfPqWp9NT1UrB__TTL31lw7oCgh0VicQH-ouc/edit -->

1. Deckhouse следит за ресурсами [ClusterLoggingConfig](cr.html#clusterloggingconfig), [ClusterLogDestination](cr.html#clusterlogdestination) и [PodLoggingConfig](cr.html#podloggingconfig).
   Комбинация конфигурации для сбора логов и направления для отправки называется `pipeline`.
2. Deckhouse генерирует конфигурационный файл и сохраняет его в `Secret` в Kubernetes.
3. `Secret` монтируется всем подам агентов `log-shipper`, конфигурация обновляется при ее изменении с помощью sidecar-контейнера `reloader`.

## Топологии отправки

Этот модуль отвечает за агентов на каждом узле. Однако подразумевается, что логи из кластера отправляются согласно одной из описанных ниже топологий.

### Распределенная

Агенты шлют логи напрямую в хранилище, например в Loki или Elasticsearch.

![log-shipper distributed](../../images/460-log-shipper/log_shipper_distributed.svg)
<!-- Исходник картинок: https://docs.google.com/drawings/d/1FFuPgpDHUGRdkMgpVWXxUXvfZTsasUhEh8XNz7JuCTQ/edit -->

* Менее сложная схема для использования.
* Доступна из коробки без лишних зависимостей, кроме хранилища.
* Сложные трансформации потребляют больше ресурсов на узлах для приложений.

### Централизованная

Все логи отсылаются в один из доступных агрегаторов, например, Logstash, Vector.
Агенты на узлах стараются отправить логи с узла максимально быстро с минимальным потреблением ресурсов.
Сложные преобразования применяются на стороне агрегатора.

![log-shipper centralized](../../images/460-log-shipper/log_shipper_centralized.svg)
<!-- Исходник картинок: https://docs.google.com/drawings/d/1TL-YUBk0CKSJuKtRVV44M9bnYMq6G8FpNRjxGxfeAhQ/edit -->

* Меньше потребление ресурсов для приложений на узлах.
* Пользователи могут настроить в агрегаторе любые трансформации и слать логи в гораздо большее количество хранилищ.
* Количество выделенных узлов под агрегаторы может увеличиваться вверх и вниз в зависимости от нагрузки.

### Потоковая

Главная задача данной архитектуры — как можно быстрее отправить логи в очередь сообщений, из которой они в служебном порядке будут переданы в долгосрочное хранилище для дальнейшего анализа.

![log-shipper stream](../../images/460-log-shipper/log_shipper_stream.svg)
<!-- Исходник картинок: https://docs.google.com/drawings/d/1R7vbJPl93DZPdrkSWNGfUOh0sWEAKnCfGkXOvRvK3mQ/edit -->

* Те же плюсы и минусы, что и у централизованной архитектуры, но добавляется еще одно промежуточное хранилище.
* Повышенная надежность. Подходит тем, для кого доставка логов является наиболее критичной.

## Метаданные

При сборе логов сообщения будут обогащены метаданными в зависимости от способа их сбора. Обогащение происходит на этапе `Source`.

### Kubernetes

Следующие поля будут экспортированы:

| Label        | Pod spec path           |
|--------------|-------------------------|
| `pod`        | metadata.name           |
| `namespace`  | metadata.namespace      |
| `pod_labels` | metadata.labels         |
| `pod_ip`     | status.podIP            |
| `image`      | spec.containers[].image |
| `container`  | spec.containers[].name  |
| `node`       | spec.nodeName           |
| `pod_owner`  | metadata.ownerRef[0]    |

| Label        | Node spec path                            |
|--------------|-------------------------------------------|
| `node_group` | metadata.labels[].node.deckhouse.io/group |

{% alert -%}
Для Splunk поля `pod_labels` не экспортируются, потому что это вложенный объект, который не поддерживается самим Splunk.
{%- endalert %}

### File

Единственный лейбл — это `host`, в котором записан hostname сервера.

## Фильтры сообщений

Существуют два фильтра, чтобы снизить количество отправляемых сообщений в хранилище, — `log filter` и `label filter`.

![log-shipper pipeline](../../images/460-log-shipper/log_shipper_pipeline.svg)
<!-- Исходник картинок: https://docs.google.com/drawings/d/1SnC29zf4Tse4vlW_wfzhggAeTDY2o9wx9nWAZa_A6RM/edit -->

Они запускаются сразу после объединения строк с помощью multiline parser'а.

1. `label filter` — правила запускаются для метаданных сообщения. Поля для метаданных (или лейблов) наполняются на основании источника логов, так что для разных источников будет разный набор полей. Эти правила полезны, например, чтобы отбросить сообщения от определенного контейнера или пода с/без какой-то метки.
2. `log filter` — правила запускаются для исходного сообщения. Есть возможность отбросить сообщение на основании JSON-поля или, если сообщение не в формате JSON, использовать регулярное выражение для поиска по строке.

Оба фильтра имеют одинаковую структурированную конфигурацию:
* `field` — источник данных для запуска фильтрации (чаще всего это значение label'а или поля из JSON-документа).
* `operator` — действие для сравнения, доступные варианты — In, NotIn, Regex, NotRegex, Exists, DoesNotExist.
* `values` — эта опция имеет разные значения для разных операторов:
  * DoesNotExist, Exists — не поддерживается;
  * In, NotIn — значение поля должно равняться или не равняться одному из значений в списке values;
  * Regex, NotRegex — значение должно подходить хотя бы под одно или не подходить ни под одно регулярное выражение из списка values.

Вы можете найти больше примеров в разделе [Примеры](examples.html) документации.

{% alert -%}
Extra labels добавляются на этапе `Destination`, поэтому невозможно фильтровать логи на их основании.
{%- endalert %}
